home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / hdf / specs / hdfspecs.lha / HDFSpecs.ch3 < prev    next >
Text File  |  1992-03-04  |  14KB  |  395 lines
  1. 3.1    NCSA HDF Specifications
  2.  
  3. Sets and Groups    3.1
  4.  
  5. National Center for Supercomputing Applications
  6.  
  7. March 1989
  8.  
  9.                                                                 
  10.  
  11.  
  12.  
  13.  
  14. 3.1    NCSA HDF Specifications
  15.  
  16. Sets and Groups    3.1
  17.  
  18. National Center for Supercomputing Applications
  19.  
  20. March 1989
  21.  
  22.                                                                 
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30. Chapter 3    Sets and Groups
  31.  
  32.  
  33.  
  34. Chapter Overview
  35. Sets
  36. Types of Sets
  37. Calling Interfaces for Sets
  38. Groups
  39. Sample Groups
  40. General Features of Groups
  41. Raster Image Sets
  42. Raster-8 Set
  43. Raster Image Set
  44. Tags for Raster Image Sets
  45. Compression of Raster Images
  46. Compatibility between Raster-8 and Raster 
  47. Image Sets
  48. Scientific Datasets
  49. Required Tags
  50. Optional Tags
  51.  
  52. Chapter Overview
  53.  
  54. This chapter describes raster image sets and scientific datasets, 
  55. explains the role of sets and groups in an HDF file, and discusses 
  56. the routines that are available for storing and retrieving scientific 
  57. datasets.
  58.  
  59.  
  60. Sets
  61.  
  62. Sometimes tags are grouped into sets, where each set is designed to 
  63. serve a particular user requirement. For example, the raster 
  64. image set, which is described in the following sections, contains 
  65. several tags that are used for storing information about 8-bit raster 
  66. images.
  67.  
  68. One advantage of using sets is that it allows different sites to 
  69. implement different parts of the entire HDF specification. When 
  70. you take an HDF file to a new site, you obtain a list of supported sets 
  71. and your file is perfectly valid for operations dealing with those 
  72. sets. Other data which you may have stored in your file is ignored 
  73. at that site but is still there when you transfer the file back.
  74.  
  75. Each HDF set is defined in terms of a minimum collection of data 
  76. objects that must be present when the set is used. For instance, 
  77. every raster image set must contain at least the following three 
  78. data objects:  an image dimension record, which gives the width 
  79. and height of the corresponding image; raster image data, which 
  80. consists of the pixel values that make up the image; and a raster 
  81. image group, which lists of all of the members in the set.
  82.  
  83. In addition, there are optional data objects that may be included in 
  84. a set. A raster image set, for instance, often contains a palette, or 
  85. lookup table, which gives the red, green, and blue values to be 
  86. associated with each pixel in the raster image data.
  87.  
  88.  
  89. Types of Sets
  90. At this time, three sets have been implemented╤two sets for storing 
  91. 8-bit raster images, and a scientific dataset for storing sets of 
  92. floating-point numbers. Specifications are given for these sets in 
  93. following sections.
  94.  
  95. Some important sets that may be added later include:
  96.  
  97. Utility set    basic utilities
  98. Utility II    suggested utilities
  99. Composite set    combinations of tags and movie organization
  100. Vector    vector and polygon images
  101. Raster image set    extension of raster set to 24-bit images
  102.  
  103.  
  104. Calling Interfaces for Sets
  105. NCSA provides calling interfaces for all the HDF sets that it 
  106. supports. The primary purpose of these calling interfaces is to 
  107. provide libraries of routines for reading and writing the data that 
  108. is associated with each set. The libraries currently supported at 
  109. NCSA are callable from either C or Fortran programs. 
  110.  
  111. In addition to the libraries, a growing number of command-line 
  112. utility routines are available for working with sets. For example, a 
  113. utility called r8tohdf is an HDF command that converts one or 
  114. more raw raster images to HDF 8-bit raster image set  format.
  115.  
  116. NCSA supports calling interfaces for the following machines:  
  117. Cray (UNICOS), Alliant (Concentrix), Silicon Graphics (UNIX), 
  118. Sun (UNIX), Macintosh (MacOS), and IBM PC/AT (MS-DOS). The 
  119. calling interfaces that are currently available are described in the 
  120. NCSA HDF manual.
  121.  
  122.  
  123. Groups
  124.  
  125. An HDF set is a collection of HDF data objects in a file. Unless 
  126. some mechanism is used to identify explicitly those objects that 
  127. belong to a set, there is often no way to tie them together. This 
  128. problem is solved in HDF by means of groups. A group is a data 
  129. object that explicitly identifies all of the data objects in a set.
  130.  
  131. Since a group is a type of data object, its structure is like that of any 
  132. other data object. A group data identifier (tag/ref) points to a data 
  133. element that consists of the collection of data identifiers that make 
  134. up the corresponding set. A group tag can be defined for any set. 
  135. For instance, raster image group (RIG) is the group tag used to 
  136. group members of raster image sets; RIG data consists of a list of 
  137. all data identifiers that belong to a particular raster image set.
  138.  
  139. Groups provide a convenient mechanism for application programs 
  140. to locate all of the information that they need about a set. 
  141. Application programs that deal with RIGs, for instance, read all of 
  142. the elements in a RIG group, using only those that they need for 
  143. their application and ignoring the others.
  144.  
  145.  
  146. Sample Groups
  147. Suppose that the two images shown in Figure 1.5 are organized into 
  148. two sets with group tags. Since they are images, they may be stored 
  149. as RIG groups. Figure 3.1 illustrates the type of organization that 
  150. incorporates RIG groupings of these images.
  151. Figure 3.1    Physical 
  152. Organization of 
  153. Sample RIG 
  154. Groupings
  155.  
  156.  Offset    Contents
  157.     0    FH
  158.     4    DDH    (5    0L)
  159.     10    DD    (FID    1    130    4)
  160.     22    DD    (FD    1    134    41)
  161.     34    DD    (IP8    1    175    768)
  162.     46    DD    (ID    1    943    4)
  163.     58    DD    (RI    1    947    240000)
  164.     70    DD    (ID    2    240947    4)
  165.     82    DD    (RI    2    240951    240,000)
  166.     94    DD    (RIG    1    480951    12)
  167.     106    DD    (RIG    2    480963    12)
  168.     118    DD    (empty)
  169.     130    "sw3"
  170.     134    "solar wind simulation:  third try. 8/8/88"
  171.     175    <data for image palette>
  172.     943    <data for 1st image dimension rec>: 400, 600
  173.     947    <data for 1st raster image>
  174.     240947    <data for 2nd image dimension rec>: 400, 600
  175.     240951    <data for 2nd raster image>
  176.     480951    tag/refs for 1st RIG:  IP8/1, ID/1, RI/1
  177.     480963    tag/refs for 2nd RIG:  IP8/1, ID/2, RI/2
  178.  
  179.  
  180.  
  181. The HDF file structure depicted in Figure 3.1 reflects the grouping 
  182. of raster image sets. This file contains the same raster image 
  183. information as the file in Figure 1.5, but the information is 
  184. organized into two sets and groups. Note that there is only one 
  185. palette (IP8/1) and it is included in both groups.
  186.  
  187.  
  188. General Features of Groups
  189. Figure 3.1 also illustrates a number of important general features 
  190. of groups:
  191.  
  192. Ñ    The contents of each set are consistent with one another. Since 
  193. the palette (IP8) is designed for use with 8-bit images, the image 
  194. must be an 8-bit image, rather than a 24-bit, 12-bit, or other 
  195. image.
  196.  
  197. Ñ    An application program can easily process all of the images in 
  198. the file by accessing the groups in the file. The non-RIG 
  199. information contained in the file can be either used or ignored, 
  200. depending on the needs and capabilities of the application 
  201. program.
  202.  
  203. Ñ    There is usually more than one way to group sets. For example, 
  204. an extra copy of the image palette (IP8) could have been stored in 
  205. the file, so that each grouping would have its own image palette. 
  206. But in this instance that is not necessary because the same 
  207. palette is to be used with both images. On the other hand, in this 
  208. example there are two image dimension records (one per group), 
  209. even though one would suffice.
  210.  
  211. Ñ    Group status does not alter the fundamental role of HDF objects. 
  212. They are still accessible as individual data objects, despite the 
  213. fact that they also belong to raster image sets. In a very real 
  214. sense, the individual data elements are in the file, whether or 
  215. not there are groups that contain them.
  216.  
  217. What each of the RIGs does is provide an index showing what 
  218. sets exist and what their members are. There is nothing to 
  219. prevent the imposition of other groupings (indexes) that provide 
  220. a different view of the same collection of data objects. In fact, 
  221. HDF is designed to encourage the addition of alternate views, 
  222. when appropriate.
  223.  
  224.  
  225. Raster Image Sets
  226.  
  227. There are currently two sets for handling raster images:  the 
  228. raster-8 set and the raster image set. The raster-8 set was the first 
  229. raster set to be implemented.  It includes a small set of data objects 
  230. for efficiently storing and retrieving color raster images.  The 
  231. raster image set is more powerful, but it is also more complex.  
  232. Raster image sets can include more detailed information about a 
  233. raster image than a raster-8 set can.  Both sets are supported by 
  234. HDF software.
  235.  
  236.  
  237. The Raster-8 Set
  238. The raster-8 set is a set of tags that provide the basic information 
  239. necessary to store 8-bit raster images in a data file and display 
  240. them accurately without prompting the user to supply dimensions 
  241. or color information. The raster-8 set consists of the tags presented 
  242. in Table 3.1.
  243.  
  244. Table 3.1    Tags for Raster-8 Sets
  245. Tag    Contents of Data Element
  246. RI8    eight-bit raster image data
  247. CI8    eight-bit raster image data compressed with
  248.     run-length encoding
  249. II8    IMCOMP compressed image data
  250. ID8    image dimension record
  251. IP8    image palette data
  252.  
  253. Even though the raster-8 set is minimal and is superseded in most 
  254. applications by the raster image set, some implementations may 
  255. want to deal with this type of data in a rough form for prototyping or 
  256. simple applications. The data stored is compatible with the raster 
  257. image set. For more information, refer to the section entitled 
  258. "Compatibility Between Raster-8 and Raster Images Sets."
  259.  
  260. If you develop software for processing raster-8 sets, it must support 
  261. RI8, ID8, and IP8. If you do not implement CI8 or II8, then be sure to 
  262. provide appropriate error indicators to higher layers that might 
  263. expect to find these tags.
  264.  
  265.  
  266. The Raster Image Set
  267. The raster image set provides a framework for storing images and 
  268. any number of optional image descriptors. It provides for a 
  269. description of the image data layout, with the optional presence of 
  270. color look-up tables, aspect ratio, color correction, associated matte 
  271. or other overlay information, or any other data related to the 
  272. display of the image.
  273.  
  274. Tying everything together is the raster image group (RIG), 
  275. examples of which were given earlier (Figure 3.1). A RIG contains 
  276. a list of data identifiers that point in turn to the data objects that 
  277. describe and make up the image.
  278.  
  279. The number of entries in a RIG is variable and the presence of 
  280. most of the description information is optional. Complex 
  281. applications can store data identifiers of image-modifying data, 
  282. such as the color table and aspect ratio, in the RIG along with the 
  283. reference to the image data itself. Simple applications can use 
  284. simple application level calls and ignore specialized video 
  285. production or film color correction parameters.
  286.  
  287. NCSA currently supports a calling interface, documented in the 
  288. NCSA HDF manual, defined for the easy storage and retrieval of 
  289. 8-bit raster images using RIGs. The interface is called RIS8 and it 
  290. handles 8-bit color tables and different compression capabilities. 
  291. Calling interfaces for storing 24-bit images and other special 
  292. cases are under development.
  293.  
  294.  
  295. Tags for Raster Image Sets
  296. The tags presented in Table 3.2 must be fully supported by any 
  297. raster image set implementation.
  298.  
  299. Table 3.2    Tags for Raster 
  300. Image Sets
  301. Tag    Contents of Data Element
  302. RIG    raster image group
  303. ID    image dimension record
  304. RI    raster image data
  305.  
  306. With full support for the above tags, images can be stored and read 
  307. from HDF files at any bit depth, with several different component 
  308. ordering schemes. Colors would be up to the calling program to 
  309. assign if the image is not in true color. In addition to the required 
  310. tags that just define an image dataset, the tags listed in Table 3.3 
  311. define color properties and other image features. These tags are 
  312. described fully in Appendix A.
  313.  
  314. Table 3.3    Additional Tags for 
  315. Raster Image Sets
  316. Tag    Contents of Data Element
  317. XYP    XY position of image
  318. LD    look-up table dimension record
  319. LUT    color look-up table for non true-color images
  320. MD    matte channel dimension record
  321. MA    matte channel data
  322. CCN    color correction factors
  323. CFM    color format designation
  324. AR    aspect ratio
  325. MTO    machine-type override
  326.  
  327.  
  328. Compression of Raster 
  329. Images
  330. Tags for two types of compression have been defined for raster 
  331. images. They are run-length encoding (RLE) and IMCOMP 
  332. aerial averaging (IMC). Each encoding tag is documented under 
  333. its specific tag type (see Appendix A). Support for RIG and RI does 
  334. not require that all of the compression tag types be supported. If you 
  335. find an unknown compression type, provide a suitable error 
  336. message to the user.
  337.  
  338.  
  339. Compatibility between 
  340. Raster-8 and Raster Image 
  341. Sets
  342. In order to maintain backward compatibility with raster-8 sets, 
  343. raster image set interfaces store tag/refs for both types of sets in 
  344. HDF raster image files. For example, if an image is stored as part 
  345. of a raster image set, there will be one copy each of the image 
  346. dimension data, image data, and palette data stored, but there will 
  347. be two sets of tag/refs pointing to each data element, one from each 
  348. set. The image data, for instance, will be associated with tag RI8 
  349. and RI.
  350.  
  351.  
  352. Scientific Datasets
  353.  
  354. The scientific dataset defines a scientific data group, which can 
  355. contain a variable number of scientific data descriptors. Current 
  356. specifications only support floating-point scientific data organized 
  357. in rectangular grid arrays. Rank and dimension sizes may vary. 
  358. A user interface exists for storing and retrieving scientific 
  359. datasets. See the NCSA HDF manual for details.
  360.  
  361.  
  362. Required Tags
  363. HDF scientific datasets must always contain at least the data 
  364. objects listed in Table 3.4.
  365.  
  366. Table 3.4    Required Tags for 
  367. Scientific Datasets
  368. Tag    Contents of Data Element
  369. SDG    scientific data group
  370. SDD    scientific data dimension record for array-stored 
  371. data. It includes the rank (number of dimensions) 
  372. and the size of each dimension.
  373. SD    scientific data
  374.  
  375. Optional Tags
  376. The data objects presented in Table 3.5 are optional. Inclusion of 
  377. these objects is supported by NCSA's user interface for scientific 
  378. datasets.
  379.  
  380. Table 3.5    Optional Tags for 
  381. Scientific Datasets
  382. Tag    Contents of Data Element
  383. SDS    scales along the different dimensions to be used when 
  384. interpreting or displaying the data
  385. SDL    labels for all dimensions and for the data. Each of the 
  386. dimension labels can be interpreted as an independent 
  387. variable, and the data label as the dependent variable.
  388. SDU    units for all dimensions and for the data
  389. SDF    format specifications to be used when displaying 
  390. values of the data
  391. SDM    maximum and minimum values of the data
  392. SDC    coordinate system to be used when interpreting or 
  393. displaying the data
  394.  
  395.